.TH "NETCONF Session" 3 "Wed Jan 28 2015" "Version 0.9.0-33_trunk" "libnetconf" \" -*- nroff -*-
.ad l
.nh
.SH NAME
NETCONF Session \- 
.PP
libnetconf's functions for handling NETCONF sessions\&.  

.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBnc_msgid\fP   char*"
.br
.RI "\fIType representing NETCONF message-id attribute\&. \fP"
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBNC_SESSION_STATUS\fP { \fBNC_SESSION_STATUS_ERROR\fP = -1, \fBNC_SESSION_STATUS_STARTUP\fP = 0, \fBNC_SESSION_STATUS_WORKING\fP = 1, \fBNC_SESSION_STATUS_CLOSING\fP = 2, \fBNC_SESSION_STATUS_CLOSED\fP = 3, \fBNC_SESSION_STATUS_DUMMY\fP = 4 }"
.br
.RI "\fIEnumeration of the possible states of a NETCONF session\&. \fP"
.ti -1c
.RI "enum \fBNC_SESSION_TERM_REASON\fP { \fBNC_SESSION_TERM_CLOSED\fP, \fBNC_SESSION_TERM_KILLED\fP, \fBNC_SESSION_TERM_DROPPED\fP, \fBNC_SESSION_TERM_TIMEOUT\fP, \fBNC_SESSION_TERM_BADHELLO\fP, \fBNC_SESSION_TERM_OTHER\fP }"
.br
.RI "\fIEnumeration of reasons of the NETCONF session termination as defined in RFC 6470\&. \fP"
.ti -1c
.RI "enum \fBNC_SSH_AUTH_TYPE\fP { \fBNC_SSH_AUTH_PUBLIC_KEYS\fP = 1, \fBNC_SSH_AUTH_PASSWORD\fP = 2, \fBNC_SSH_AUTH_INTERACTIVE\fP = 4 }"
.br
.RI "\fIAvailable SSH authentication mechanisms\&. \fP"
.ti -1c
.RI "enum \fBNC_TRANSPORT\fP { \fBNC_TRANSPORT_UNKNOWN\fP = -1, \fBNC_TRANSPORT_SSH\fP, \fBNC_TRANSPORT_TLS\fP }"
.br
.RI "\fISupported NETCONF transport protocols enumeration\&. To change currently used transport protocol, call \fBnc_session_transport()\fP\&. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBnc_callback_ssh_host_authenticity_check\fP (int(*func)(const char *hostname, LIBSSH2_SESSION *session))"
.br
.RI "\fISet a callback function to authorize authenticity of the remote host\&. \fP"
.ti -1c
.RI "void \fBnc_callback_sshauth_interactive\fP (void(*func)(const char *name, int name_len, const char *instruction, int instruction_len, int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, void **abstract))"
.br
.RI "\fISet a callback function for passing user credentials into the libssh2's keyboard-interactive authentication method\&. \fP"
.ti -1c
.RI "void \fBnc_callback_sshauth_passphrase\fP (char *(*func)(const char *username, const char *hostname, const char *priv_key_file))"
.br
.RI "\fISet a callback function for passing the user password into the libssh2's publickey authentication method when connecting to 'hostname' as 'username'\&. \fP"
.ti -1c
.RI "void \fBnc_callback_sshauth_password\fP (char *(*func)(const char *username, const char *hostname))"
.br
.RI "\fISet a callback function for passing the user password into the libssh2's password authentication method when connecting to 'hostname' as 'username'\&. \fP"
.ti -1c
.RI "int \fBnc_cpblts_add\fP (struct nc_cpblts *capabilities, const char *capability_string)"
.br
.RI "\fIAdd another capability string into the NETCONF capabilities structure\&. \fP"
.ti -1c
.RI "int \fBnc_cpblts_count\fP (const struct nc_cpblts *c)"
.br
.RI "\fIGet the number of capabilities in the structure\&. \fP"
.ti -1c
.RI "int \fBnc_cpblts_enabled\fP (const struct nc_session *session, const char *capability_string)"
.br
.RI "\fICheck if the given capability is supported by the session\&. \fP"
.ti -1c
.RI "void \fBnc_cpblts_free\fP (struct nc_cpblts *c)"
.br
.RI "\fIFree NETCONF capabilities structure\&. \fP"
.ti -1c
.RI "const char * \fBnc_cpblts_get\fP (const struct nc_cpblts *c, const char *capability_string)"
.br
.RI "\fIGet complete capability string including parameters\&. \fP"
.ti -1c
.RI "const char * \fBnc_cpblts_iter_next\fP (struct nc_cpblts *c)"
.br
.RI "\fIGet the next capability string from the given NETCONF capabilities structure\&. \fP"
.ti -1c
.RI "void \fBnc_cpblts_iter_start\fP (struct nc_cpblts *c)"
.br
.RI "\fIMove NETCONF capabilities structure iterator to the beginning of the capability strings list\&. \fP"
.ti -1c
.RI "struct nc_cpblts * \fBnc_cpblts_new\fP (const char *const list[])"
.br
.RI "\fICreate a new NETCONF capabilities structure\&. \fP"
.ti -1c
.RI "int \fBnc_cpblts_remove\fP (struct nc_cpblts *capabilities, const char *capability_string)"
.br
.RI "\fIRemove the specified capability string from the NETCONF capabilities structure\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_accept\fP (const struct nc_cpblts *capabilities)"
.br
.RI "\fIAccept NETCONF session from a client\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_accept_inout\fP (const struct nc_cpblts *capabilities, const char *username, int input, int output)"
.br
.RI "\fIAccept NETCONF session from a client\&. It allows to assign the specified username to it and set file descriptors for reading/writing NETCONF data\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_accept_username\fP (const struct nc_cpblts *capabilities, const char *username)"
.br
.RI "\fIAccept NETCONF session from a client and assign it to the specified username\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_connect\fP (const char *host, unsigned short port, const char *username, const struct nc_cpblts *cpblts)"
.br
.RI "\fICreate NETCONF session to the specified server\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_connect_channel\fP (struct nc_session *session, const struct nc_cpblts *cpblts)"
.br
.RI "\fICreate another NETCONF session using already established SSH session\&. No authentication is needed in this case\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_connect_inout\fP (int fd_in, int fd_out, const struct nc_cpblts *cpblts, const char *host, const char *port, const char *username, \fBNC_TRANSPORT\fP transport)"
.br
.RI "\fICreate NETCONF session communicating via given file descriptors\&. This is an alternative function to \fBnc_session_connect()\fP\&. \fP"
.ti -1c
.RI "struct nc_session * \fBnc_session_dummy\fP (const char *sid, const char *username, const char *hostname, struct nc_cpblts *capabilities)"
.br
.RI "\fICreate a disconnected session structure\&. \fP"
.ti -1c
.RI "void \fBnc_session_free\fP (struct nc_session *session)"
.br
.RI "\fICleanup the session structure and free all the allocated resources\&. \fP"
.ti -1c
.RI "struct nc_cpblts * \fBnc_session_get_cpblts\fP (const struct nc_session *session)"
.br
.RI "\fIGet list of capabilities associated with the session\&. \fP"
.ti -1c
.RI "struct nc_cpblts * \fBnc_session_get_cpblts_default\fP (void)"
.br
.RI "\fIGet NULL terminated list of the default capabilities supported by libnetconf including the list of namespaces provided by the datastores created with \fBncds_new()\fP and initialized by \fBncds_init()\fP\&. \fP"
.ti -1c
.RI "int \fBnc_session_get_eventfd\fP (const struct nc_session *session)"
.br
.RI "\fIGet the input file descriptor to asynchronous control of input events\&. \fP"
.ti -1c
.RI "const char * \fBnc_session_get_host\fP (const struct nc_session *session)"
.br
.RI "\fIGet NETCONF session host\&. \fP"
.ti -1c
.RI "const char * \fBnc_session_get_id\fP (const struct nc_session *session)"
.br
.RI "\fIGet NETCONF session ID\&. \fP"
.ti -1c
.RI "const char * \fBnc_session_get_port\fP (const struct nc_session *session)"
.br
.RI "\fIGet NETCONF session port number\&. \fP"
.ti -1c
.RI "\fBNC_SESSION_STATUS\fP \fBnc_session_get_status\fP (const struct nc_session *session)"
.br
.RI "\fIGet information about the session current status\&. \fP"
.ti -1c
.RI "\fBNC_TRANSPORT\fP \fBnc_session_get_transport\fP (const struct nc_session *session)"
.br
.RI "\fIGet transport protocol used for the NETCONF session\&. \fP"
.ti -1c
.RI "const char * \fBnc_session_get_user\fP (const struct nc_session *session)"
.br
.RI "\fIGet NETCONF session username\&. \fP"
.ti -1c
.RI "int \fBnc_session_get_version\fP (const struct nc_session *session)"
.br
.RI "\fIGet NETCONF protocol version used in the given session\&. \fP"
.ti -1c
.RI "int \fBnc_session_monitor\fP (struct nc_session *session)"
.br
.RI "\fIAdd the session into the internal list of monitored sessions that are returned as part of netconf-state information defined in RFC 6022\&. \fP"
.ti -1c
.RI "int \fBnc_session_notif_allowed\fP (struct nc_session *session)"
.br
.RI "\fITell me if the notification subscription is allowed on the given session\&. \fP"
.ti -1c
.RI "int \fBnc_session_transport\fP (\fBNC_TRANSPORT\fP proto)"
.br
.RI "\fISet transport protocol for the sessions created by subsequent \fBnc_session_connect()\fP calls\&. By default, transport protocol is set to \fBNC_TRANSPORT_SSH\fP\&. \fP"
.ti -1c
.RI "void \fBnc_set_keypair_path\fP (const char *privkey, const char *pubkey)"
.br
.RI "\fISet path to a private and a public key file used in case of SSH authentication via a publickey mechanism\&. \fP"
.ti -1c
.RI "void \fBnc_ssh_pref\fP (\fBNC_SSH_AUTH_TYPE\fP type, short int preference)"
.br
.RI "\fISet the preference of the SSH authentication methods\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
libnetconf's functions for handling NETCONF sessions\&. 


.SH "Macro Definition Documentation"
.PP 
.SS "#define nc_msgid   char*"

.PP
Type representing NETCONF message-id attribute\&. It corresponds to the following typedef: typedef char* nc_msgid;
.PP
We use a macro to avoid compiler warning of 'const nc_msgid' as return type of functions (because const is applied as 'char* const funct()' which is meaningless)\&.
.PP
Yes, I know that const char* means 'pointer to constant character (not
string)', but I want to be clear from the API, that function returns pointer to something that should not be changed\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBNC_SESSION_STATUS\fP"

.PP
Enumeration of the possible states of a NETCONF session\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_SESSION_STATUS_ERROR \fP\fP
undefined status or the error return code 
.TP
\fB\fINC_SESSION_STATUS_STARTUP \fP\fP
session is setting up 
.TP
\fB\fINC_SESSION_STATUS_WORKING \fP\fP
session is established and ready to work 
.TP
\fB\fINC_SESSION_STATUS_CLOSING \fP\fP
session is being closed 
.TP
\fB\fINC_SESSION_STATUS_CLOSED \fP\fP
session was closed and could not be used for communication 
.TP
\fB\fINC_SESSION_STATUS_DUMMY \fP\fP
session is DUMMY, only holds information, does not provide connection 
.SS "enum \fBNC_SESSION_TERM_REASON\fP"

.PP
Enumeration of reasons of the NETCONF session termination as defined in RFC 6470\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_SESSION_TERM_CLOSED \fP\fP
closed by client in a normal fashion 
.TP
\fB\fINC_SESSION_TERM_KILLED \fP\fP
session was terminated by <kill-session> operation 
.TP
\fB\fINC_SESSION_TERM_DROPPED \fP\fP
transport layer connection was unexpectedly closed 
.TP
\fB\fINC_SESSION_TERM_TIMEOUT \fP\fP
terminated because of inactivity 
.TP
\fB\fINC_SESSION_TERM_BADHELLO \fP\fP
<hello> message was invalid 
.TP
\fB\fINC_SESSION_TERM_OTHER \fP\fP
terminated for some other reason 
.SS "enum \fBNC_SSH_AUTH_TYPE\fP"

.PP
Available SSH authentication mechanisms\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_SSH_AUTH_PUBLIC_KEYS \fP\fP
SSH user authorization via publickeys 
.TP
\fB\fINC_SSH_AUTH_PASSWORD \fP\fP
SSH user authorization via password 
.TP
\fB\fINC_SSH_AUTH_INTERACTIVE \fP\fP
interactive SSH user authorization 
.SS "enum \fBNC_TRANSPORT\fP"

.PP
Supported NETCONF transport protocols enumeration\&. To change currently used transport protocol, call \fBnc_session_transport()\fP\&. Note that NC_TRANSPORT_TLS is supported only when libnetconf is compiled with --enable-tls configure's option\&. If the option is not used, \fBnc_session_transport()\fP returns EXIT_FAILURE with NC_TRANSPORT_TLS value\&.
.PP
This setting is valuable only for client side NETCONF applications\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_TRANSPORT_UNKNOWN \fP\fP
Unknown transport protocol, this is not acceptable as input value 
.TP
\fB\fINC_TRANSPORT_SSH \fP\fP
NETCONF over SSH, this value is used by default 
.TP
\fB\fINC_TRANSPORT_TLS \fP\fP
NETCONF over TLS 
.SH "Function Documentation"
.PP 
.SS "void nc_callback_ssh_host_authenticity_check (int(*)(const char *hostname, LIBSSH2_SESSION *session)func)"

.PP
Set a callback function to authorize authenticity of the remote host\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP\&.
.PP
If the func parameter is NULL, the callback is set back to the default function\&.
.PP
\fBParameters:\fP
.RS 4
\fIfunc\fP Callback function to use\&. Expected callback return values are:
.IP "\(bu" 2
EXIT_SUCCESS - hosts and keys match, the SSH session establishment will continue\&.
.IP "\(bu" 2
EXIT_FAILURE - keys do not match or an error occurred\&. 
.PP
.RE
.PP

.SS "void nc_callback_sshauth_interactive (void(*)(const char *name, int name_len, const char *instruction, int instruction_len, int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, void **abstract)func)"

.PP
Set a callback function for passing user credentials into the libssh2's keyboard-interactive authentication method\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP\&.
.PP
If the func parameter is NULL, the callback is set back to the default function\&.
.PP
\fBParameters:\fP
.RS 4
\fIfunc\fP Callback function to use\&. For more information about the callback parameters, see libssh2_userauth_keyboard_interactive() description in libssh2 documentation\&. 
.RE
.PP

.SS "void nc_callback_sshauth_passphrase (char *(*)(const char *username, const char *hostname, const char *priv_key_file)func)"

.PP
Set a callback function for passing the user password into the libssh2's publickey authentication method when connecting to 'hostname' as 'username'\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP\&.
.PP
If the func parameter is NULL, the callback is set back to the default function\&.
.PP
\fBParameters:\fP
.RS 4
\fIfunc\fP Callback function to use\&. 
.RE
.PP

.SS "void nc_callback_sshauth_password (char *(*)(const char *username, const char *hostname)func)"

.PP
Set a callback function for passing the user password into the libssh2's password authentication method when connecting to 'hostname' as 'username'\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP\&.
.PP
If the func parameter is NULL, the callback is set back to the default function\&.
.PP
\fBParameters:\fP
.RS 4
\fIfunc\fP Callback function to use\&. The callback function should return a password string for the given username and name of the remote host\&. 
.RE
.PP

.SS "int nc_cpblts_add (struct nc_cpblts *capabilities, const char *capability_string)"

.PP
Add another capability string into the NETCONF capabilities structure\&. This function is NOT thread safe\&.
.PP
\fBParameters:\fP
.RS 4
\fIcapabilities\fP Current NETCONF capabilities structure\&. 
.br
\fIcapability_string\fP Capability string to add\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success
.br
 non-zero on error 
.RE
.PP

.SS "int nc_cpblts_count (const struct nc_cpblts *c)"

.PP
Get the number of capabilities in the structure\&. Use this function to get the count of capabilities held by nc_cpblts structure\&.
.PP
\fBParameters:\fP
.RS 4
\fIc\fP NETCONF capabilities structure\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Number of capabilities held by structure c\&. 
.RE
.PP

.SS "int nc_cpblts_enabled (const struct nc_session *session, const char *capability_string)"

.PP
Check if the given capability is supported by the session\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Established session where the given capability support will be checked\&. 
.br
\fIcapability_string\fP NETCONF capability string to check\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 for false result, 1 if the given capability is supported\&. 
.RE
.PP

.SS "void nc_cpblts_free (struct nc_cpblts *c)"

.PP
Free NETCONF capabilities structure\&. This function is NOT thread safe\&.
.PP
\fBParameters:\fP
.RS 4
\fIc\fP Capabilities structure to free\&. 
.RE
.PP

.SS "const char* nc_cpblts_get (const struct nc_cpblts *c, const char *capability_string)"

.PP
Get complete capability string including parameters\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP Capabilities structure to be examined 
.br
\fIcapability_string\fP Capability identifier, parameters are ignored and only basic identifier is used to retrieve specific identifier including parameters from the given capability structure\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Constant capability identifier including parameters 
.RE
.PP

.SS "const char* nc_cpblts_iter_next (struct nc_cpblts *c)"

.PP
Get the next capability string from the given NETCONF capabilities structure\&. To move iterator to the beginning of the capability strings list, use \fBnc_cpblts_iter_start()\fP\&.
.PP
This function is NOT thread safe\&.
.PP
\fBParameters:\fP
.RS 4
\fIc\fP NETCONF capabilities structure to be iterated\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Another capability string, NULL if all strings were already returned\&. 
.RE
.PP

.SS "void nc_cpblts_iter_start (struct nc_cpblts *c)"

.PP
Move NETCONF capabilities structure iterator to the beginning of the capability strings list\&. This function is NOT thread safe\&.
.PP
\fBParameters:\fP
.RS 4
\fIc\fP NETCONF capabilities structure to be iterated\&. 
.RE
.PP

.SS "struct nc_cpblts* nc_cpblts_new (const char *constlist[])"

.PP
Create a new NETCONF capabilities structure\&. 
.PP
\fBParameters:\fP
.RS 4
\fIlist\fP NULL terminated list of capabilities strings to initially add into the NETCONF capabilities structure\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Created NETCONF capabilities structure\&. 
.RE
.PP

.SS "int nc_cpblts_remove (struct nc_cpblts *capabilities, const char *capability_string)"

.PP
Remove the specified capability string from the NETCONF capabilities structure\&. This function is NOT thread safe\&.
.PP
\fBParameters:\fP
.RS 4
\fIcapabilities\fP Current NETCONF capabilities structure\&. 
.br
\fIcapability_string\fP Capability string to remove\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success
.br
 non-zero on error 
.RE
.PP

.SS "struct nc_session* nc_session_accept (const struct nc_cpblts *capabilities)"

.PP
Accept NETCONF session from a client\&. The caller process of this function is supposed to be launched as a subprocess of the transport protocol server (in case of SSH, it is called SSH Subsystem)\&. Username assigned to the NETCONF session is guessed from the process's UID\&. This approach supposes that the transport protocol server launches the caller process with the changed UID according to the user logged in (OpenSSH's sshd does this, stunnel does not - see \fBnc_session_accept_username()\fP instead of this function)\&.
.PP
Only one NETCONF session can be accepted in a single caller since it communicates with the transport protocol server directly via (redirected) stdin and stdout streams\&.
.PP
\fBParameters:\fP
.RS 4
\fIcapabilities\fP NETCONF capabilities structure with the capabilities supported by the server\&. The caller can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing the accepted NETCONF session or NULL in case of an error\&. 
.RE
.PP

.SS "struct nc_session* nc_session_accept_inout (const struct nc_cpblts *capabilities, const char *username, intinput, intoutput)"

.PP
Accept NETCONF session from a client\&. It allows to assign the specified username to it and set file descriptors for reading/writing NETCONF data\&. The same as \fBnc_session_accept_username()\fP except that it allows caller to set file descriptors where the libnetconf will read/write NETCONF (unencrypted) data\&.
.PP
\fBParameters:\fP
.RS 4
\fIcapabilities\fP NETCONF capabilities structure with the capabilities supported by the server\&. The caller can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.br
\fIusername\fP Name of the user which will be assigned to the NETCONF session\&. This information is used for example by NACM subsystem\&. If NULL, the function act the same way as the \fBnc_session_accept()\fP function\&. 
.br
\fIinput\fP File descriptor from which the NETCONF data will be read\&. 
.br
\fIoutput\fP File descriptor to which the NETCONF data will be written\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing the accepted NETCONF session or NULL in case of an error\&. 
.RE
.PP

.SS "struct nc_session* nc_session_accept_username (const struct nc_cpblts *capabilities, const char *username)"

.PP
Accept NETCONF session from a client and assign it to the specified username\&. The same as \fBnc_session_accept()\fP except that instead of guessing username from the process's UID, the specified username is assigned to the NETCONF session\&. This can be used especially in case that the transport protocol server (sshd, stunnel,\&.\&.\&.) does not change process's UID automatically\&.
.PP
\fBParameters:\fP
.RS 4
\fIcapabilities\fP NETCONF capabilities structure with the capabilities supported by the server\&. The caller can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.br
\fIusername\fP Name of the user which will be assigned to the NETCONF session\&. This information is used for example by NACM subsystem\&. If NULL, the function act the same way as the \fBnc_session_accept()\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing the accepted NETCONF session or NULL in case of an error\&. 
.RE
.PP

.SS "struct nc_session* nc_session_connect (const char *host, unsigned shortport, const char *username, const struct nc_cpblts *cpblts)"

.PP
Create NETCONF session to the specified server\&. This function can internally use various callbacks set by the client to perform SSH authentication\&. It selects authentication mechanism from the list provided by the SSH server and based on the preferences set by the client via \fBnc_ssh_pref()\fP\&. Then, appropriate callback function (set by \fBnc_callback_sshauth_password()\fP, \fBnc_callback_sshauth_passphrase()\fP, nc_set_publickey_path() or nc_set_privatekey_path()) is used to perform the authentication\&.
.PP
\fBParameters:\fP
.RS 4
\fIhost\fP Hostname or address (both Ipv4 and IPv6 are accepted)\&. 'localhost' is used by default if NULL is specified\&. 
.br
\fIport\fP Port number of the server\&. Default value 830 is used if 0 is specified\&. 
.br
\fIusername\fP Name of the user to login to the server\&. The user running the application (detected from the effective UID) is used if NULL is specified\&. 
.br
\fIcpblts\fP NETCONF capabilities structure with capabilities supported by the client\&. Client can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing the NETCONF session or NULL in case of an error\&. 
.RE
.PP

.SS "struct nc_session* nc_session_connect_channel (struct nc_session *session, const struct nc_cpblts *cpblts)"

.PP
Create another NETCONF session using already established SSH session\&. No authentication is needed in this case\&. This function works only if libnetconf is compiled with using libssh2\&.
.PP
It is not applicable to the sessions created by \fBnc_session_connect_inout()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Already established NETCONF session using \fBnc_session_connect()\fP\&. 
.br
\fIcpblts\fP NETCONF capabilities structure with capabilities supported by the client\&. Client can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing the NETCONF session or NULL in case of an error\&. 
.RE
.PP

.SS "struct nc_session* nc_session_connect_inout (intfd_in, intfd_out, const struct nc_cpblts *cpblts, const char *host, const char *port, const char *username, \fBNC_TRANSPORT\fPtransport)"

.PP
Create NETCONF session communicating via given file descriptors\&. This is an alternative function to \fBnc_session_connect()\fP\&. In this case the initiation of the transport session (SSH, TLS, \&.\&.\&.) is done externally\&. libnetconf just uses provided file descriptors to read data from and write data to that external entity (process, functions,\&.\&.\&.)\&.
.PP
Before calling this function, all necessary authentication process must be done so libnetconf can directly start with <hello> messages performing the NETCONF handshake\&.
.PP
Since connecting to a host and authentication is done before, the provided host, port, username anf transport arguments are only informative and libnetconf use them only for returning value by nc_session_get_*() functions\&. The cpblts argument is used during the NETCONF handshake in the same way as in the \fBnc_session_connect()\fP function\&.
.PP
It is not allowed to use \fBnc_session_connect_channel()\fP on the session created by this function\&.
.PP
\fBParameters:\fP
.RS 4
\fIfd_in\fP Opened file desriptor where the (unencrypted) data from the NETCONF server are read\&. 
.br
\fIfd_out\fP Opened file desriptor where the (unencrypted) data to the NETCONF server are written\&. 
.br
\fIcpblts\fP NETCONF capabilities structure with capabilities supported by the client\&. Client can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.br
\fIhost\fP Name of the host where we are connected to via the provided file descriptors\&. 
.br
\fIport\fP The port number of the remote host where we are connected\&. 
.br
\fIusername\fP Name of the user we are connected to the remote host as\&. 
.br
\fItransport\fP The transport protocol used to connect to the remote host\&. 
.RE
.PP

.SS "struct nc_session* nc_session_dummy (const char *sid, const char *username, const char *hostname, struct nc_cpblts *capabilities)"

.PP
Create a disconnected session structure\&. This creates a dummy session structure which is not supposed to exchange NETCONF messages between client and server\&. Instead, it can be successfully used by server (e\&.g\&. detached process that doesn't hold the real session structure) to access NETCONF datastores via libnetconf\&.
.PP
All the required parameters can be obtained from the real session structure by the session getter functions (\fBnc_session_get_id()\fP, \fBnc_session_get_user()\fP and \fBnc_session_get_cpblts()\fP)\&. NULL values are not allowed\&.
.PP
\fBParameters:\fP
.RS 4
\fIsid\fP Session ID\&. 
.br
\fIusername\fP Name of the user holding the session\&. 
.br
\fIhostname\fP Name (domain name, IP) of the opposite communication side (optional parameter, can be NULL)\&. 
.br
\fIcapabilities\fP List of capabilities supported by the session\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing a dummy NETCONF session or NULL in case of an error\&. 
.RE
.PP

.SS "void nc_session_free (struct nc_session *session)"

.PP
Cleanup the session structure and free all the allocated resources\&. Do not use the given session structure after this call\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session to free\&. 
.RE
.PP

.SS "struct nc_cpblts* nc_session_get_cpblts (const struct nc_session *session)"

.PP
Get list of capabilities associated with the session\&. Returned structure is connected with the session\&. Do not free or modify it\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
NETCONF capabilities structure containing capabilities associated with the given session\&. NULL is returned on error\&. 
.RE
.PP

.SS "struct nc_cpblts* nc_session_get_cpblts_default (void)"

.PP
Get NULL terminated list of the default capabilities supported by libnetconf including the list of namespaces provided by the datastores created with \fBncds_new()\fP and initialized by \fBncds_init()\fP\&. The caller is supposed to free the returned structure with \fBnc_cpblts_free()\fP\&.
.PP
\fBReturns:\fP
.RS 4
NETCONF capabilities structure containing capabilities supported by libnetconf\&. 
.RE
.PP

.SS "int nc_session_get_eventfd (const struct nc_session *session)"

.PP
Get the input file descriptor to asynchronous control of input events\&. The caller must avoid direct reading from the returned file descriptor\&. It is supposed to be used only by select, poll, epoll or an event library (e\&.g\&. libevent)\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
Input file descriptor of the communication channel\&. 
.RE
.PP

.SS "const char* nc_session_get_host (const struct nc_session *session)"

.PP
Get NETCONF session host\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
Constant string identifying NETCONF session server host\&. 
.RE
.PP

.SS "const char* nc_session_get_id (const struct nc_session *session)"

.PP
Get NETCONF session ID\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
Constant string identifying NETCONF session\&. 
.RE
.PP

.SS "const char* nc_session_get_port (const struct nc_session *session)"

.PP
Get NETCONF session port number\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
Constant string identifying NETCONF session server host\&. 
.RE
.PP

.SS "\fBNC_SESSION_STATUS\fP nc_session_get_status (const struct nc_session *session)"

.PP
Get information about the session current status\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
NETCONF session status\&. 
.RE
.PP

.SS "\fBNC_TRANSPORT\fP nc_session_get_transport (const struct nc_session *session)"

.PP
Get transport protocol used for the NETCONF session\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
one of NC_TRANSPORT enumeration values\&. 
.RE
.PP

.SS "const char* nc_session_get_user (const struct nc_session *session)"

.PP
Get NETCONF session username\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
Constant string identifying NETCONF session server host\&. 
.RE
.PP

.SS "int nc_session_get_version (const struct nc_session *session)"

.PP
Get NETCONF protocol version used in the given session\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
NETCONF protocol version, 0 for 1\&.0, 1 for 1\&.1 
.RE
.PP

.SS "int nc_session_monitor (struct nc_session *session)"

.PP
Add the session into the internal list of monitored sessions that are returned as part of netconf-state information defined in RFC 6022\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session to be monitored; 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int nc_session_notif_allowed (struct nc_session *session)"

.PP
Tell me if the notification subscription is allowed on the given session\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session structure 
.RE
.PP
\fBReturns:\fP
.RS 4
0 if not, 1 if subscription is currently allowed\&. 
.RE
.PP

.SS "int nc_session_transport (\fBNC_TRANSPORT\fPproto)"

.PP
Set transport protocol for the sessions created by subsequent \fBnc_session_connect()\fP calls\&. By default, transport protocol is set to \fBNC_TRANSPORT_SSH\fP\&. This function is thread-safe\&. Change made by calling this function applies only to the current thread\&. 
.SS "void nc_set_keypair_path (const char *privkey, const char *pubkey)"

.PP
Set path to a private and a public key file used in case of SSH authentication via a publickey mechanism\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIprivkey\fP Path to the private key file\&. 
.br
\fIpubkey\fP Path to the public key file 
.RE
.PP

.SS "void nc_ssh_pref (\fBNC_SSH_AUTH_TYPE\fPtype, short intpreference)"

.PP
Set the preference of the SSH authentication methods\&. Allowed authentication types are defined as NC_SSH_AUTH_TYPE type\&. The default preferences are:
.IP "1." 4
interactive (3)
.IP "2." 4
password (2)
.IP "3." 4
public keys (1)
.PP
.PP
This function has no effect with configure's --disable-libssh2 option\&.
.PP
To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP header file\&.
.PP
\fBParameters:\fP
.RS 4
\fItype\fP Setting preference for the given authentication type\&. 
.br
\fIpreference\fP Preference value\&. Higher value means higher preference\&. Negative value disables the given authentication type\&. On equality of values, the last set authentication type is preferred\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libnetconf from the source code\&.
